FishMarket 1.0/FishMarket v1.0.iso/fishies/051-075/disk_069/conman/conman.doc

Text File | 1992-05-06 | 8KB | 152 lines

*************************     ConMan v0.9     **************************

ConMan is a replacement console handler that provides line editing and
command line histories.  It runs under AmigaDOS (V1.1 or V1.2) and is
completely transparent to any application program that uses CON: windows.
Programs that use RAW: input are unaffected.

Once installed, any windows opened by AmigaDOS will automatically open
using the ConMan handler.  This includes command windows opened by
NEWCLI as well as any data input/output windows that your program uses.

Line Editing.
The DELETE and BACKSPACE keys function in the usual manner.  The arrow keys
may be used for cursor positioning.  The shifted left arrow moves the cursor
to the beginning of the line, and the shift right arrow moves to the end.

The default input mode inserts characters at the cursor; overstrike may
be toggled by CTRL-A.  CTRL-X deletes the whole line, while CTRL-Y
deletes from the cursor position to the end of the line.
Tabs are replaced by blanks, so you can back up over them properly.

Command History.
Previously-entered lines may be recalled using the up-arrow.  Lines are
retrieved sequentially; if you go past the one you want, the down-arrow
key will back up one.  Shift up-arrow goes to the oldest line, and shift
down-arrow positions the pointer to the most recent line.  The current
history buffer holds ten input lines; this will be made variable in a
later release.

Window definition.
ConMan supports the usual DOS window specification string.  For example,
"CON:160/50/320/100/MyWindow" specifies a window 320x100 pixels in size,
beginning in position (160,50).  ConMan also accepts a specification in
the form "CON:x20480", where the hex digits following the "x" are the
absolute address of an Intuition window pointer.  If you're writing in
'C', the following sequence would serve to open a window and attach a
DOS console to it:

      window = OpenWindow(&newwindow);   /* get a window          */
      sprintf(buffer,"CON:X%x",window);  /* build the name string */
      file  = Open(buffer,MODE_OLDFILE); /* open a console stream */

The more arcane method of passing the window pointer to the handler
(as in Andy Finkel's Window example) should also work, but I haven't
tried it yet. (Let me know, if someone tries it).

Late-breaking news: at the suggestion of John Toebes, I've added the
ability to select which gadgets and attributes your window will have.
Here's how it works:  After the last numeric parameter, put a backslash
and any of the attribute options:
   A ==> activate             (def: no activate)
   B ==> BackDrop             (def: not BackDrop)
   C ==> Close gadget         (def: no gadget) (action not implemented)
   D ==> Depth gadget         (def: depth gadget)
   M ==> Move (drag) gadget   (def: drag gadget)
   N ==> NoBorder             (def: border) (sorry, 'B' was used)
   S ==> Sizing gadget        (def: sizing gadget)
   Z ==> Zero-Zero            (def: not GZZ) (does anybody use this?)
Each attribute serves to TOGGLE the corresponding windows flag, so adding
it twice will cancel the effect.  Follow the list with a terminating '/'
and an optional title.

Example: CON:10/10/300/100\nb/       creates a borderless backdrop window.
         CON:10/10/300/100\acm/Fixed creates an active window, with a
                                     close gadget, that won't budge.

One more addition: specifying CON:s123abc/10/10/300/100/ will attach
your window to the specified CUSTOMSCREEN.  I only tried it on the
workbench screen, though (by digging the screen pointer out of
IntuitionBase).  Let me know if it works on real custom screens.

Installation.
ConMan requires that two files be copied to your SYS: disk (don't worry,
they're both small.)  "My-Handler" (144 bytes) must be placed in
the SYS:L directory, to keep all those bigger handlers company.  The
"conhandlerlib.library" (4164 bytes) must be placed in the your LIBS:
directory, which is normally SYS:LIBS.  Once these files are present,
execute ConMan (852 bytes) to install the handler.  This file only needs
to be run once (e.g. from your startup-sequence); it allocates 20 bytes
of memory for the handler name string which won't be returned (there are
no provisions in DOS for removing handlers, anyway.)  The ARCed files
have shortened names, so be sure to rename "conlib.lib" and "myhandlr."
A simple "install" script is included to copy files.

Distribution.
This program is to be distributed as shareware to Amigoid life-forms
everywhere!  Make sure your friends get a copy.  Comments and contributions
will be appreciated and may be sent to:

      William S. Hawes
      P.O. Box 308
      Maynard, MA 01754
      [phone]

Further Notes.
This Beta version still has some debugging code in it.  Function key F1
toggles a flag that causes a DisplayBeep everytime a WaitForChar packet
is dispatched.  Most programs will not use the WaitForChar function,
since a Read to a CON: device will block until characters are available
anyway.  F2 toggles a flag that DisplayBeeps whenever a "break" signal is
passed on (i.e. is applied to your hapless task).

The program was developed and tested under V1.2; at least one V1.1
dependency was found and fixed (DoIO to the console device scratched D7).
Let me know if other problems exist.  I spent a lot of time making it
work using the DOS handler-loading mechanism so that it would be backwards
compatible.

ConMan does not pre-allocate a history buffer for the commands, but
rather allocates just enough for each string.  This means that the
available memory changes after every command ... the memory isn't lost,
but it makes it difficult to tell if a program under development is
misbehaving.  This will be changed in the next release.

Some of the things I'm thinking about adding include:
   -- Support for the function keys and help keys.  I'm designing a
      general-purpose data structure to support context-sensitive
      function and help key definitions.  Keys should support both
      string-substitution and event-type actions.  Any ideas in these
      directions?

   -- The ConMan handler is built as a standard shared library.  Various
      entry points will be brought out and documented, and procedural
      calls will be available to manipulate the internal data structures.
      This will allow you to retrieve the window pointer by something
      straightforward like "window = ConsoleWindow(filehandle);".
      I may even write the binding routines for calls from 'C' ...

   -- How about adding a "dynamic piping" capability, so that an I/O
      stream could be diverted on the fly into (or out of) a file?  Ideas?

   -- I plan to release the source code (in assembler) once things are
      cleaned up a bit.  It will be very helpful to anyone needing to
      write a DOS handler.  In the meantime, take a look at the included
      "handler.asm" file:  it provides a simple way around the problem
      of writing BCPL look-alike programs.

   -- Another tip:  debugging handlers is easy if you try the following
      trick.  Run the handler program as a normal process under your
      favorite debugger.  Have it open a public message port, which can
      located by a test driver running separately.  The driver now
      installs your processid ("pr_MsgPort, obtained by following the
      MP_SIGTASK trail from your public port) in its "pr_ConsoleTask" slot,
      and then does an Open('*',MODE_OLDFILE).  Voila!  Any I/O done by
      the driver comes under the scrutiny of your debugger.  You can
      get things working before having to worry about installing the
      handler in a device node.  (An occasional message collision will
      occur, since the debugger is probably doing I/O through the
      processid message port.  Not to worry ...)

                                   -- WSH (4/14/87)